DDBEnhanced - Support to flatten a Map into top level attributes of the object #6102

anasatirbasa · 2025-05-14T07:25:28Z

Added the facility of using an annotation that will flatten a map of attributes in a class,
similar to what @DynamoDbFlatten does for attributes from another class.

Description

Added a new annotation named DynamoDbFlattenMap that can be applied at method level for only a single map of attributes within a class (Map<String, String>). If used on multiple maps of attributes, the serialization will throw an exception.

Motivation and Context

#2542

Modifications

Followed the same approach as for DybamoDbFlatten annotation, that is used to flatten all the attributes of a separate DynamoDb bean that is stored in the current bean

Testing

The changes have already been tested by running the existing tests and also added new unit/integration tests for the new flow.

Test Coverage Checklist

Scenario	Done	Comments if Not Done
1. Different TableSchema Creation Methods
a. TableSchema.fromBean(Customer.class)	[x]
b. TableSchema.fromImmutableClass(Customer.class) for immutable classes	[x]
c. TableSchema.documentSchemaBuilder().build()	[ ]
d. StaticTableSchema.builder(Customer.class)	[x]
2. Nesting of Different TableSchema Types
a. @DynamoDbBean with nested @DynamoDbBean as NonNull	[x]
b. @DynamoDbBean with nested @DynamoDbImmutable as NonNull	[x]
c. @DynamoDbImmutable with nested @DynamoDbBean as NonNull	[x]
d. @DynamoDbBean with nested @DynamoDbBean as Null	[x]
e. @DynamoDbBean with nested @DynamoDbImmutable as Null	[x]
f. @DynamoDbImmutable with nested @DynamoDbBean as Null	[x]
3. CRUD Operations
a. scan()	[ ]
b. query()	[x]
c. updateItem()	[x]
d. putItem()	[x]
e. getItem()	[x]
f. deleteItem()	[ ]
g. batchGetItem()	[ ]
h. batchWriteItem()	[ ]
i. transactGetItems()	[ ]
j. transactWriteItems()	[ ]
4. Data Types and Null Handling
a. top-level null attributes	[x]
b. collections with null elements	[x]
c. maps with null values	[x]
d. conversion between null Java values and AttributeValue	[ ]
e. full serialization/deserialization cycle with null values	[ ]
5. AsyncTable and SyncTable
a. DynamoDbAsyncTable Testing	[ ]
b. DynamoDbTable Testing	[ ]
6. New/Modification in Extensions
a. Tables with Scenario in ScenarioSl No.1 (All table schemas are Must)	[ ]
b. Test with Default Values in Annotations	[ ]
c. Combination of Annotation and Builder passes extension	[ ]
7. New/Modification in Converters
a. Tables with Scenario in ScenarioSl No.1 (All table schemas are Must)	[ ]
b. Test with Default Values in Annotations	[ ]
c. Test All Scenarios from 1 to 5	[ ]

Screenshots (if appropriate)

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)

Checklist

I have read the CONTRIBUTING document
Local run of mvn install succeeds
My code follows the code style of this project
My change requires a change to the Javadoc documentation
I have updated the Javadoc documentation accordingly
I have added tests to cover my changes
All new and existing tests passed
I have added a changelog entry. Adding a new entry must be accomplished by running the scripts/new-change script and following the instructions. Commit the new file created by the script in .changes/next-release with your changes.
My change is to implement 1.11 parity feature and I have updated LaunchChangelog

License

I confirm that this pull request can be released under the Apache 2 license

…he object

alextwoods · 2025-09-04T17:30:53Z

.changes/next-release/feature-AmazonDynamoDBEnhancedClient-22723fc.json

+    "type": "feature",
+    "category": "Amazon DynamoDB Enhanced Client",
+    "contributor": "",
+    "description": "Added the support to flatten a Map into top level attributes of the object"


Nit: mention the annotation name here. Maybe:

Add support for @DynamoDBFlattenMap to flatten a Map to top level attributes of an object

alextwoods · 2025-09-04T17:39:41Z

services-custom/dynamodb-enhanced/README.md

@@ -685,3 +685,53 @@ private static final StaticTableSchema<Customer> CUSTOMER_TABLE_SCHEMA =
 ```
 Just as for annotations, you can flatten as many different eligible classes as you like using the
 builder pattern. 
+
+#### Using composition


There is already a "Using composition" header above this (so this already falls under that section).

I think ths should be its own ### level header instead - maybe "### Flattening map attributes"

alextwoods · 2025-09-04T17:40:00Z

services-custom/dynamodb-enhanced/README.md

+
+#### Using composition
+
+Using composition, the @DynamoDBFlattenMap annotation support to flatten a Map:


this reads a bit weirdly, consider rephrasing.

alextwoods · 2025-09-04T17:41:28Z

services-custom/dynamodb-enhanced/README.md

+    public void setDetailsMap(Map<String, String> record) { this.detailsMap = detailsMap;}
+}
+```
+You can flatten only one map present on a record, otherwise it will be thrown an exception


May want to add that this includes maps on any flattened classes as well.

Phrasing nit: "otherwise it will be thrown an exception" -> "otherwise an exception will be thrown".

Additionally - are there other constraints we should mention here? What key and value types are supported? It is only <String, String>?

alextwoods · 2025-09-04T17:47:15Z

services-custom/dynamodb-enhanced/README.md

+
+    @DynamoDbFlattenMap
+    public Map<String, String> getDetailsMap() { return this.detailsMap; }
+    public void setDetailsMap(Map<String, String> record) { this.detailsMap = detailsMap;}


parameter name record here is incorrect, it should be detailsMap.

Suggested change

public void setDetailsMap(Map<String, String> record) { this.detailsMap = detailsMap;}

public void setDetailsMap(Map<String, String> detailsMap) { this.detailsMap = detailsMap;}

alextwoods · 2025-09-04T19:30:41Z

...rc/main/java/software/amazon/awssdk/enhanced/dynamodb/mapper/StaticImmutableTableSchema.java

+        private Map<String, AttributeValue> itemToMap(T item, boolean ignoreNulls, List<String> attributeNames) {
+            Map<String, String> mapItem = this.mapItemGetter.apply(item);
+
+            Map<String, AttributeValue> result  = new HashMap<>();


white space nit - make sure you've run checkstyle.

Suggested change

Map<String, AttributeValue> result = new HashMap<>();

Map<String, AttributeValue> result = new HashMap<>();

alextwoods · 2025-09-04T19:31:39Z

services-custom/dynamodb-enhanced/README.md

+                                      .setter(Customer::setName))
+    // Because we are flattening a Map object, we supply a getter and setter so the
+    // mapper knows how to access it
+    .flattenMap(Map::detailsMap, Map::detailsMap)


Suggested change

.flattenMap(Map::detailsMap, Map::detailsMap)

.flattenMap(Map::getDetailsMap, Map::setDetailsMap)

alextwoods · 2025-09-04T19:59:36Z

...d/src/test/java/software/amazon/awssdk/enhanced/dynamodb/functionaltests/FlattenMapTest.java

+    }
+
+    @Test
+    public void updateItemWithFlattenMap_withDuplicateAttributeName_throwsIllegalArgumentException() {


Can we also add a similar test for behavior with the FlattenMapAndFlattenRecordBean with a duplicate attribute in the flattened record?

alextwoods · 2025-09-04T20:08:24Z

...-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/mapper/BeanTableSchema.java

@@ -286,6 +302,15 @@ private static Optional<Method> findFluentSetter(Class<?> beanClass, String prop
                     .findFirst();
    }

+    private static boolean dynamoDbFlattenMapAnnotationHasInvalidUse(List<PropertyDescriptor> mappableProperties) {


Sorry more validation questions - what about cases where multiple traits are applied, eg:

@DynamoDbUpdateBehavior(UpdateBehavior.WRITE_IF_NOT_EXISTS) @DynamoDbFlattenMap public Map<String, String> getDetailsMap() { return this.detailsMap; }

alextwoods · 2025-09-04T20:09:53Z

...tom/dynamodb-enhanced/src/it/java/software/amazon/awssdk/enhanced/dynamodb/model/Record.java

@@ -27,6 +28,8 @@ public class Record {

    private String stringAttribute;

+    private Map<String, String> attributesMap;


This is a generic question - not specifically related to this line only.

We are only supporting maps of <String, String> with this change right?

How could we extend this to support different value types long term - at minimum I'd think the standard types we support, potentially even allowing custom attribute converters to be applied.

I think releasing this with only String values is probably reasonable, but I want to make sure that we could add more support in the future without it being a breaking change.

anasatirbasa requested a review from a team as a code owner May 14, 2025 07:25

anasatirbasa force-pushed the feature/support-to-flatten-a-map branch 9 times, most recently from 25598b0 to fab983f Compare May 23, 2025 11:48

DDBEnhanced - Support to flatten a Map into top level attributes of t…

b0979f4

…he object

anasatirbasa force-pushed the feature/support-to-flatten-a-map branch from fab983f to b0979f4 Compare May 27, 2025 11:09

alextwoods and others added 2 commits August 29, 2025 14:57

Merge branch 'master' into feature/support-to-flatten-a-map

a3b3db7

Merge branch 'master' into feature/support-to-flatten-a-map

e438149

alextwoods requested changes Sep 4, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

DDBEnhanced - Support to flatten a Map into top level attributes of the object #6102

DDBEnhanced - Support to flatten a Map into top level attributes of the object #6102

Uh oh!

anasatirbasa commented May 14, 2025 •

edited

Loading

Uh oh!

alextwoods Sep 4, 2025

Uh oh!

alextwoods Sep 4, 2025

Uh oh!

alextwoods Sep 4, 2025

Uh oh!

alextwoods Sep 4, 2025

Uh oh!

alextwoods Sep 4, 2025

Uh oh!

alextwoods Sep 4, 2025

Uh oh!

alextwoods Sep 4, 2025

Uh oh!

alextwoods Sep 4, 2025

Uh oh!

alextwoods Sep 4, 2025

Uh oh!

alextwoods Sep 4, 2025

Uh oh!

Uh oh!


		#### Using composition

		Using composition, the @DynamoDBFlattenMap annotation support to flatten a Map:

	public void setDetailsMap(Map<String, String> record) { this.detailsMap = detailsMap;}
	public void setDetailsMap(Map<String, String> detailsMap) { this.detailsMap = detailsMap;}

	Map<String, AttributeValue> result = new HashMap<>();
	Map<String, AttributeValue> result = new HashMap<>();

	.flattenMap(Map::detailsMap, Map::detailsMap)
	.flattenMap(Map::getDetailsMap, Map::setDetailsMap)

		@@ -27,6 +28,8 @@ public class Record {

		private String stringAttribute;

		private Map<String, String> attributesMap;

DDBEnhanced - Support to flatten a Map into top level attributes of the object #6102

Are you sure you want to change the base?

DDBEnhanced - Support to flatten a Map into top level attributes of the object #6102

Uh oh!

Conversation

anasatirbasa commented May 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and Context

Modifications

Testing

Test Coverage Checklist

Screenshots (if appropriate)

Types of changes

Checklist

License

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

anasatirbasa commented May 14, 2025 •

edited

Loading